/**
 * Software License, Version 1.0
 * 
 * Copyright 2003 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgement:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgement may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or NaradaBrokering, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called NaradaBrokering, 
 * nor may Indiana University or Community Grids Lab or NaradaBrokering appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 *LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 *WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 *NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 *INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 *INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 *"VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 *LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 *ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 *GENERATED USING SOFTWARE.
 */
package cgl.narada.wsinfra.wse.matching;

import org.apache.xmlbeans.XmlCursor;

import cgl.narada.wsinfra.exception.ProcessingException;
import cgl.narada.wsinfra.schemas.eventing.FilterType;
import cgl.narada.wsinfra.schemas.soap.EnvelopeDocument;
/**
    This is an interface which snapshots the capability of matching. Users
    can develop their custom engines and register these at run-time. For e.g.
    there could implementations of this for XPath, XQuery, String Topics and
    Regular Expressions. Other custom capabilities can be added by the
    developers and registered at run-time.

    @author Shrideep Pallickara
    $Date: 2005/07/29 22:41:30 $
    $Revision: 1.6 $
*/


public abstract class MatchingCapability {

  private final 
  String defaultDialect = "http://www.w3.org/TR/1999/REC-xpath-19991116";

  /** Retrieves the dialects associated with the matching capability */
  public abstract String getDialect();

  /** Retrieves the name associated with this capability. */
  public abstract String getCapabilityName();

  
  /** Perform the matching operation.
      @return true If there is a match
      @return false If there isn't a match */
  public abstract boolean 
  performMatching(EnvelopeDocument envelopeDocument, FilterType filter)
    throws ProcessingException;
  

  /** Checks the envelope document for problems. */
  public void checkEnvelopeForProblems(EnvelopeDocument envelopeDocument) 
    throws ProcessingException  {
    if (envelopeDocument == null) {
      String errorReport = getCapabilityName() + 
	"The specified Envelope is NULL";
      throw 
	new ProcessingException(errorReport);
    }
  }
  
  
  /** Checks the filter for problems and returns the constraint associated
      with this filter. */
  public String checkFilterForProblems(FilterType filter) 
    throws ProcessingException {
    String errorReport = getCapabilityName();
    if (filter == null) {
      errorReport = "The specified filter is NULL!";
    }
    
    XmlCursor filterCursor = filter.newCursor();
    String constraint = filterCursor.getTextValue();
    filterCursor.dispose();
    
    boolean filterProblems = false;
    
    if (constraint == null) {
      errorReport = "The constraint contained within the filter is NULL." +
	" This is not a Valid Value\n";
      filterProblems = true;
    }
    
    String filterDialect = null;
    if (!filter.isSetDialect()) {
      filterDialect = defaultDialect;
    } else {
      filterDialect = filter.getDialect();
    }
    
    String capabilityDialect = getDialect();
    if (!filterDialect.equals(capabilityDialect)) { 
      errorReport += "The Dialect supported by this capability is [" +
	capabilityDialect + "] while the one contained (or implied, if one " +
	"is missing) within the filter is [" +	filterDialect + "]";
      filterProblems = true;
    }
    
    
    if (filterProblems == true) {
      throw new ProcessingException(errorReport);
    }

    return constraint;
  }

}
